Inside Macintosh: QuickDraw GX Objects /

Chapter 1 - Introduction to QuickDraw GX / The QuickDraw GX Programming Environment

Programming Conventions and Consistencies

The QuickDraw GX programming environment provides many consistent features and conventions to make graphics software development more convenient and more efficient. This section lists some of them.

Object Behavior

Many QuickDraw GX objects have similar features and consistent behavior, in ways such as the following:

• In general, setting a property of an object causes action or new behavior only when needed--which may not be immediately. For example, setting the gxDiskShape attribute of a shape object, which instructs QuickDraw GX to write the shape to disk, takes effect only as soon as QuickDraw GX needs memory space and looks for objects to unload.
• QuickDraw GX handles object properties consistently; it does not change a property once you have set it. For example, if you set an object reference to nil in order to use the default version of an object, QuickDraw GX does not replace that nil value with an actual reference. If you later make another call to retrieve that reference, you will get back the nil value you originally set. (A minor exception to this rule occurs with certain calls that assign arrays to the style object associated with typographic shapes; QuickDraw GX may alter the order of elements in those arrays. See the layout styles chapter in Inside Macintosh: QuickDraw GX Typography for more information.)
• Most objects can be explicitly moved into and out of memory, using GXLoadObject and GXUnloadObject functions. View-related objects and printing objects are exceptions to this rule.
• Many objects can have tag objects attached to them, using GXGetObjectTags and GXSetObjectTags functions. View group objects, printing objects, font objects, and tag objects themselves are exceptions to this rule.
• Most objects can be shared, and thus have GXCloneObject and GXGetObjectOwners functions. View-related objects are exceptions to this rule; they are shared but they have no owner count and cannot be cloned.

Functions and Function Results

QuickDraw GX functions are designed to operate in a consistent manner, as follows:

• Most QuickDraw GX functions do not return error codes as function results. Instead, they return object references or pointers to structures. This makes nesting of calls easier.
• Functions are consistently named and have consistent behavior across all
  objects. Most objects have similarly behaving GXNewObject, GXDisposeObject, GXCopyToObject, and GXEqualObject functions. The property-accessing GXGetObjectProperty and GXSetObjectProperty functions behave consistently, using index values and ranges for inserting, deleting, or replacing all or parts of arrays.
• All functions, except some printing functions that return an OSErr value, return nil or zero as a function result if an error occurs.
• If a function posts an error, it does not modify any data or objects that are input parameters to the function.
• Functions of the form GXGetObjectProperty that fill out an array that is passed as a parameter typically return the number of elements in that array as a function result. For example, the GXGetTransformViewPorts function, used to get the list of view port references in a transform object, returns the number of elements in the list as its function result. Thus, you commonly call such a function twice in a row: first to determine the size of array to allocate, and second to obtain the filled-out array itself.
• Many functions of the form GXSetObjectProperty, which modify a property of a particular object, have a parallel function of the form GXSetShapeProperty, which performs the same function but allows you to specify instead the shape object that references the affected object. If the object whose property is changed is not shared by more than one shape, the two functions have an identical effect. If, however the object is shared, GXSetShapeProperty makes a copy of the object before modifying it, so that the other shapes using it are not affected unintentionally.

  For example, the GXSetTransformViewPorts function assigns a list of view port references to the specified transform object, and the GXSetShapeViewPorts function assigns a list of view port references to the transform object associated with the specified shape. If the transform object is used by more than one shape, GXSetTransformViewPorts has the effect of altering all shapes that use that transform; GXSetShapeViewPorts, however, first makes a copy of the transform and then alters it, so that other shapes are not affected.

• When an out-of-memory condition occurs, it is rarely fatal. QuickDraw GX initially posts an out_of_memory error, but execution continues and subsequent attempts to reference the object responsible for the error result in posting of object_is_nil errors.
• The debugging version of QuickDraw GX provides extensive error-checking and validation capabilities to help you determine why a function call has failed.

Function Parameters

When passing parameters to a QuickDraw GX function, you can take advantage of the following design consistencies and conveniences:

• The first parameter in any function call is the object or structure acted upon.
• Parameters whose names contain the word "source" are never modified by a function; parameters whose names contain the word "target" may be modified.
• Whenever an array or structure is passed as a parameter to a function, the application is responsible for allocating it. QuickDraw GX fills out structures, but it does not allocate them.
• When a variable-sized array or structure is passed as a parameter to a function, it is preceded in the parameter list by a size or count parameter.
• In the C language definitions for QuickDraw GX functions, the term const preceding a parameter that is an array, structure, or pointer indicates that QuickDraw GX reads from, but does not write to, the data pointed to by the parameter.
• In general, passing nil or zero for a parameter instructs QuickDraw GX to use its default or most appropriate behavior for that situation. Thus you need to explicitly set parameters only when you need specific, non-default behavior. To actually assign a nil value to a property, pass the constant gxSetToNil (see Table 1-1).
• In functions that use coordinates, the x-coordinate (horizontal axis) is specified before the y-coordinate (vertical axis).
• For convenience in handling arrays and pointers in parameters, QuickDraw GX provides several predefined constants, as listed in Table 1-1.

  Table 1-1 Convenience constants for parameters

  Constant	Value	Explanation
  gxSelectToEnd	-1	Used in a size or count parameter, to mean "from the current position in the array to the end of the array."
  gxSetToNil	(void *)(-1)	Used in a parameter (where a function takes more than one parameter) to assign a nil value to a pointer or reference property (simply passing nil has no effect on the property).
  gxNoAttributes	0	Used to clear the attributes property of an object.
  gxColorValue1	0xFFFF	Used to specify the maximum value for a color-component, which is interpreted to mean 1.0
  gxAnyNumber	1	Used as an index in an array declaration to indicate that the array is not of any specific size.

Implementation limits

Limits on valid parameter values or on the sizes of structures or behaviors of objects may depend on the current implementation of QuickDraw GX, and may be different from the fundamental limits imposed by the programmatic interface itself. For example, a parameter to a function may be a long, but the range of acceptable values for that parameter may be much smaller than the full range of values that can fit into a long.

Code Naming Conventions

QuickDraw GX uses these naming conventions to provide consistency across the application interface:

• Function names begin with uppercase GX--for example, GXDrawShape. Important exceptions are those in the Collection Manager and those that are mathematical functions because those functions can be useful outside of the QuickDraw GX environment.
• Identifiers of constants and data types defined by QuickDraw GX begin with lowercase gx--for example, gxWindingFill and gxShapeType. One exception is the type Fixed, which represents a QuickDraw GX fixed-point number but does not have a gx prefix. Types defined by the programming language itself, such as short, do not have a gx prefix.
• Names of fields in data structures, and parameter names in function prototypes, begin with lowercase letters and do not have a gx prefix.
• An enumeration that defines several constants is usually named with a plural
  form--for example, gxDashAttributes. Such an enumeration is commonly paired with a type definition that is a singular form of the same name--for example, gxDashAttribute. You can use the type to specify one of the enumerated values
  for a parameter or field.
• Object attributes have suffixes that identify the kind of object they apply to. For example, dash attributes specified by the gxDashAttributes enumeration include the attributes gxBendDash and gxAutoAdvanceDash.